<?xml version="1.0" encoding="ascii"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>circuits.web.tools</title>
  <link rel="stylesheet" href="epydoc.css" type="text/css" />
  <script type="text/javascript" src="epydoc.js"></script>
</head>

<body bgcolor="white" text="black" link="blue" vlink="#204080"
      alink="#204080">
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="circuits-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Project homepage -->
      <th class="navbar" align="right" width="100%">
        <table border="0" cellpadding="0" cellspacing="0">
          <tr><th class="navbar" align="center"
            ><a class="navbar" target="_top" href="http://trac.softcircuit.com.au/circuits/">circuits</a></th>
          </tr></table></th>
  </tr>
</table>
<table width="100%" cellpadding="0" cellspacing="0">
  <tr valign="top">
    <td width="100%">
      <span class="breadcrumbs">
        <a href="circuits-module.html">Package&nbsp;circuits</a> ::
        <a href="circuits.web-module.html">Package&nbsp;web</a> ::
        Module&nbsp;tools
      </span>
    </td>
    <td>
      <table cellpadding="0" cellspacing="0">
        <!-- hide/show private -->
      </table>
    </td>
  </tr>
</table>
<!-- ==================== MODULE DESCRIPTION ==================== -->
<h1 class="epydoc">Module tools</h1><p class="nomargin-top"></p>
<p>Tools</p>
  <p>This module implements tools used throughout circuits.web. These tools
  can also be used within Controlelrs and request handlers.</p>

<!-- ==================== FUNCTIONS ==================== -->
<a name="section-Functions"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Functions</span></td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="circuits.web.tools-module.html#expires" class="summary-sig-name">expires</a>(<span class="summary-sig-arg">request</span>,
        <span class="summary-sig-arg">response</span>,
        <span class="summary-sig-arg">secs</span>=<span class="summary-sig-default">0</span>,
        <span class="summary-sig-arg">force</span>=<span class="summary-sig-default">False</span>)</span><br />
      Tool for influencing cache mechanisms using the 'Expires' header.</td>
          <td align="right" valign="top">
            
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="circuits.web.tools-module.html#serve_file" class="summary-sig-name">serve_file</a>(<span class="summary-sig-arg">request</span>,
        <span class="summary-sig-arg">response</span>,
        <span class="summary-sig-arg">path</span>,
        <span class="summary-sig-arg">type</span>=<span class="summary-sig-default">None</span>,
        <span class="summary-sig-arg">disposition</span>=<span class="summary-sig-default">None</span>,
        <span class="summary-sig-arg">name</span>=<span class="summary-sig-default">None</span>)</span><br />
      Set status, headers, and body in order to serve the given file.</td>
          <td align="right" valign="top">
            
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a name="serve_download"></a><span class="summary-sig-name">serve_download</span>(<span class="summary-sig-arg">request</span>,
        <span class="summary-sig-arg">response</span>,
        <span class="summary-sig-arg">path</span>,
        <span class="summary-sig-arg">name</span>=<span class="summary-sig-default">None</span>)</span><br />
      Serve 'path' as an application/x-download attachment.</td>
          <td align="right" valign="top">
            
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="circuits.web.tools-module.html#validate_etags" class="summary-sig-name">validate_etags</a>(<span class="summary-sig-arg">request</span>,
        <span class="summary-sig-arg">response</span>,
        <span class="summary-sig-arg">autotags</span>=<span class="summary-sig-default">False</span>)</span><br />
      Validate the current ETag against If-Match, If-None-Match headers.</td>
          <td align="right" valign="top">
            
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="circuits.web.tools-module.html#validate_since" class="summary-sig-name">validate_since</a>(<span class="summary-sig-arg">request</span>,
        <span class="summary-sig-arg">response</span>)</span><br />
      Validate the current Last-Modified against If-Modified-Since headers.</td>
          <td align="right" valign="top">
            
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a name="redirect"></a><span class="summary-sig-name">redirect</span>(<span class="summary-sig-arg">request</span>,
        <span class="summary-sig-arg">response</span>,
        <span class="summary-sig-arg">url</span>=<span class="summary-sig-default"><code class="variable-quote">'</code><code class="variable-string"></code><code class="variable-quote">'</code></span>)</span></td>
          <td align="right" valign="top">
            
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a name="trailing_slash"></a><span class="summary-sig-name">trailing_slash</span>(<span class="summary-sig-arg">request</span>,
        <span class="summary-sig-arg">response</span>,
        <span class="summary-sig-arg">missing</span>=<span class="summary-sig-default">True</span>,
        <span class="summary-sig-arg">extra</span>=<span class="summary-sig-default">False</span>)</span><br />
      Redirect if request.path has (missing|extra) trailing slash.</td>
          <td align="right" valign="top">
            
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="circuits.web.tools-module.html#flatten" class="summary-sig-name">flatten</a>(<span class="summary-sig-arg">request</span>,
        <span class="summary-sig-arg">response</span>)</span><br />
      Wrap response.body in a generator that recursively iterates over 
      body.</td>
          <td align="right" valign="top">
            
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="circuits.web.tools-module.html#check_auth" class="summary-sig-name">check_auth</a>(<span class="summary-sig-arg">request</span>,
        <span class="summary-sig-arg">response</span>,
        <span class="summary-sig-arg">users</span>,
        <span class="summary-sig-arg">encrypt</span>=<span class="summary-sig-default">None</span>,
        <span class="summary-sig-arg">realm</span>=<span class="summary-sig-default">None</span>)</span><br />
      Check Authentication</td>
          <td align="right" valign="top">
            
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="circuits.web.tools-module.html#basic_auth" class="summary-sig-name">basic_auth</a>(<span class="summary-sig-arg">request</span>,
        <span class="summary-sig-arg">response</span>,
        <span class="summary-sig-arg">realm</span>,
        <span class="summary-sig-arg">users</span>,
        <span class="summary-sig-arg">encrypt</span>=<span class="summary-sig-default">None</span>)</span><br />
      Perform Basic Authentication</td>
          <td align="right" valign="top">
            
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="circuits.web.tools-module.html#digest_auth" class="summary-sig-name">digest_auth</a>(<span class="summary-sig-arg">request</span>,
        <span class="summary-sig-arg">response</span>,
        <span class="summary-sig-arg">realm</span>,
        <span class="summary-sig-arg">users</span>)</span><br />
      Perform Digest Authentication</td>
          <td align="right" valign="top">
            
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
</table>
<!-- ==================== VARIABLES ==================== -->
<a name="section-Variables"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Variables</span></td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a name="__package__"></a><span class="summary-name">__package__</span> = <code title="'circuits.web'"><code class="variable-quote">'</code><code class="variable-string">circuits.web</code><code class="variable-quote">'</code></code>
    </td>
  </tr>
</table>
<!-- ==================== FUNCTION DETAILS ==================== -->
<a name="section-FunctionDetails"></a>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td align="left" colspan="2" class="table-header">
    <span class="table-header">Function Details</span></td>
</tr>
</table>
<a name="expires"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">expires</span>(<span class="sig-arg">request</span>,
        <span class="sig-arg">response</span>,
        <span class="sig-arg">secs</span>=<span class="sig-default">0</span>,
        <span class="sig-arg">force</span>=<span class="sig-default">False</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    >&nbsp;
    </td>
  </tr></table>
  
  <p>Tool for influencing cache mechanisms using the 'Expires' header.</p>
  <p>'secs' must be either an int or a datetime.timedelta, and indicates 
  the number of seconds between response.time and when the response should 
  expire. The 'Expires' header will be set to (response.time + secs).</p>
  <p>If 'secs' is zero, the 'Expires' header is set one year in the past, 
  and the following &quot;cache prevention&quot; headers are also set:</p>
  <ul>
    <li>
      'Pragma': 'no-cache'
    </li>
    <li>
      'Cache-Control': 'no-cache, must-revalidate'
    </li>
  </ul>
  <p>If 'force' is False (the default), the following headers are checked: 
  'Etag', 'Last-Modified', 'Age', 'Expires'. If any are already present, 
  none of the above response headers are set.</p>
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<a name="serve_file"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">serve_file</span>(<span class="sig-arg">request</span>,
        <span class="sig-arg">response</span>,
        <span class="sig-arg">path</span>,
        <span class="sig-arg">type</span>=<span class="sig-default">None</span>,
        <span class="sig-arg">disposition</span>=<span class="sig-default">None</span>,
        <span class="sig-arg">name</span>=<span class="sig-default">None</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    >&nbsp;
    </td>
  </tr></table>
  
  <p>Set status, headers, and body in order to serve the given file.</p>
  <p>The Content-Type header will be set to the type arg, if provided. If 
  not provided, the Content-Type will be guessed by the file extension of 
  the 'path' argument.</p>
  <p>If disposition is not None, the Content-Disposition header will be set
  to &quot;&lt;disposition&gt;; filename=&lt;name&gt;&quot;. If name is 
  None, it will be set to the basename of path. If disposition is None, no 
  Content-Disposition header will be written.</p>
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<a name="validate_etags"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">validate_etags</span>(<span class="sig-arg">request</span>,
        <span class="sig-arg">response</span>,
        <span class="sig-arg">autotags</span>=<span class="sig-default">False</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    >&nbsp;
    </td>
  </tr></table>
  
  <p>Validate the current ETag against If-Match, If-None-Match headers.</p>
  <p>If autotags is True, an ETag response-header value will be provided 
  from an MD5 hash of the response body (unless some other code has already
  provided an ETag header). If False (the default), the ETag will not be 
  automatic.</p>
  <p>WARNING: the autotags feature is not designed for URL's which allow 
  methods other than GET. For example, if a POST to the same URL returns no
  content, the automatic ETag will be incorrect, breaking a fundamental use
  for entity tags in a possibly destructive fashion. Likewise, if you raise
  304 Not Modified, the response body will be empty, the ETag hash will be 
  incorrect, and your application will break. See 
  http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.24</p>
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<a name="validate_since"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">validate_since</span>(<span class="sig-arg">request</span>,
        <span class="sig-arg">response</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    >&nbsp;
    </td>
  </tr></table>
  
  <p>Validate the current Last-Modified against If-Modified-Since 
  headers.</p>
  <p>If no code has set the Last-Modified response header, then no 
  validation will be performed.</p>
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<a name="flatten"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">flatten</span>(<span class="sig-arg">request</span>,
        <span class="sig-arg">response</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    >&nbsp;
    </td>
  </tr></table>
  
  <p>Wrap response.body in a generator that recursively iterates over 
  body.</p>
  <p>This allows response.body to consist of 'nested generators'; that is, 
  a set of generators that yield generators.</p>
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<a name="check_auth"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">check_auth</span>(<span class="sig-arg">request</span>,
        <span class="sig-arg">response</span>,
        <span class="sig-arg">users</span>,
        <span class="sig-arg">encrypt</span>=<span class="sig-default">None</span>,
        <span class="sig-arg">realm</span>=<span class="sig-default">None</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    >&nbsp;
    </td>
  </tr></table>
  
  <p>Check Authentication</p>
  <p>If an authorization header contains credentials, return True, else 
  False.</p>
  <dl class="fields">
    <dt>Parameters:</dt>
    <dd><ul class="nomargin-top">
        <li><strong class="pname"><code>realm</code></strong> (str) - The authentication realm.</li>
        <li><strong class="pname"><code>users</code></strong> (dict or callable) - A dict of the form: {username: password} or a callable returning 
          a dict.</li>
        <li><strong class="pname"><code>encrypt</code></strong> (callable) - Callable used to encrypt the password returned from the 
          user-agent. if None it defaults to a md5 encryption.</li>
    </ul></dd>
  </dl>
</td></tr></table>
</div>
<a name="basic_auth"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">basic_auth</span>(<span class="sig-arg">request</span>,
        <span class="sig-arg">response</span>,
        <span class="sig-arg">realm</span>,
        <span class="sig-arg">users</span>,
        <span class="sig-arg">encrypt</span>=<span class="sig-default">None</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    >&nbsp;
    </td>
  </tr></table>
  
  <p>Perform Basic Authentication</p>
  <p>If auth fails, returns an Unauthorized error  with a basic 
  authentication header.</p>
  <dl class="fields">
    <dt>Parameters:</dt>
    <dd><ul class="nomargin-top">
        <li><strong class="pname"><code>realm</code></strong> (str) - The authentication realm.</li>
        <li><strong class="pname"><code>users</code></strong> (dict or callable) - A dict of the form: {username: password} or a callable returning 
          a dict.</li>
        <li><strong class="pname"><code>encrypt</code></strong> (callable) - Callable used to encrypt the password returned from the 
          user-agent. if None it defaults to a md5 encryption.</li>
    </ul></dd>
  </dl>
</td></tr></table>
</div>
<a name="digest_auth"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">digest_auth</span>(<span class="sig-arg">request</span>,
        <span class="sig-arg">response</span>,
        <span class="sig-arg">realm</span>,
        <span class="sig-arg">users</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    >&nbsp;
    </td>
  </tr></table>
  
  <p>Perform Digest Authentication</p>
  <p>If auth fails, raise 401 with a digest authentication header.</p>
  <dl class="fields">
    <dt>Parameters:</dt>
    <dd><ul class="nomargin-top">
        <li><strong class="pname"><code>realm</code></strong> (str) - The authentication realm.</li>
        <li><strong class="pname"><code>users</code></strong> (dict or callable) - A dict of the form: {username: password} or a callable returning 
          a dict.</li>
    </ul></dd>
  </dl>
</td></tr></table>
</div>
<br />
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="circuits-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Project homepage -->
      <th class="navbar" align="right" width="100%">
        <table border="0" cellpadding="0" cellspacing="0">
          <tr><th class="navbar" align="center"
            ><a class="navbar" target="_top" href="http://trac.softcircuit.com.au/circuits/">circuits</a></th>
          </tr></table></th>
  </tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%%">
  <tr>
    <td align="left" class="footer">
    Generated by Epydoc 3.0.1 on Tue Feb  2 05:55:52 2010
    </td>
    <td align="right" class="footer">
      <a target="mainFrame" href="http://epydoc.sourceforge.net"
        >http://epydoc.sourceforge.net</a>
    </td>
  </tr>
</table>

<script type="text/javascript">
  <!--
  // Private objects are initially displayed (because if
  // javascript is turned off then we want them to be
  // visible); but by default, we want to hide them.  So hide
  // them unless we have a cookie that says to show them.
  checkCookie();
  // -->
</script>
</body>
</html>
